【扩展 API开发】DingoApi(一)

阅读数:0次 2018-10-28

DingoApi 简介

dingo/api 是一个 Lumen 和 Laravel 都可用的 RestFul 工具包，帮助我们快速的开始构建 RestFul Api，
再配合 dingo + JWT 可以用来构建后端api ,JWT在API中的应用一般用来验证用户的登录有效性。

此外，在Laravel 5.3之后引入新的官方OAuth扩展Laravel Passport，但是Passport 只是对 API 这种非 session
状态下请求的授权和验证令牌处理，不如DingoApi那样是一个整套的脚手架。

完整的脚手架包括以下这些：

1.令牌认证（JWT 或者 OAuth 2 等）
2.符合接口规范的相应数据结构
3.异常的处理（网页的异常可能直接是500页面，或者404页面，API 就不能用这些页面了）
4.返回数据的转换，不能直接把数据库查询的模型返回，而是需要一定的优化，做一个友好的 API 接口
5.请求次数限制，已经自带了
6.一个友好的 API 文档，最好能自动生成
7.良好的路由和版本控制等等

安装

Laravel 5.5 的适配版本为dingo/api:v2.0.0-alpha2

1	composer require dingo/api:2.0.0-alpha2

如果报错，可能是镜像源的问题，更换镜像

1	composer config repo.packagist composer https://packagist.laravel-china.org

如果还是错误：Your requirements could not be resolved to an installable set of packages.
这是因为这个包还在开发阶段，没有稳定的release版本，需要修改composer.json,增加两句

1 2	"minimum-stability" : "dev", "prefer-stable" : true

“minimum-stability” : “dev” ——设定的最低稳定性的版本为 dev 也就是可以依赖开发版本的扩展包；

“prefer-stable” : true —— Composer 优先使用更稳定的包版本。

配置

先将 dingo 的配置文件 publish 出来

1	php artisan vendor:publish

选择 [2 ] Provider: Dingo\Api\Provider\LaravelServiceProvider
然后在config目录下看到 api.php 文件，然后把 api.php文件中的配置提取到可以在env中修改，如：

API_STANDARDS_TREE=prs
API_SUBTYPE=beautyblog
API_PREFIX=api
API_VERSION=v1
API_DEBUG=true

详细解释如下：

API_STANDARDS_TREE 和 API_SUBTYPE

API版本推荐做法是使用Accept 头来指定我们需要访问的 API 版本。

1	Accept: application/<API_STANDARDS_TREE>.<API_SUBTYPE>.v1+json

API_STANDARDS_TREE 有是三个值可选:

x 本地开发的或私有环境的

prs 未对外发布的，提供给公司 app，单页应用，桌面应用等
vnd 对外发布的，开放给所有用户
API_STANDARDS_TREE可以暂时选择prs:
1
API_STANDARDS_TREE=prs

API_SUBTYPE一般是项目的简称，如 beautyblog

可以通过如下方式来访问不同版本的 API

访问 v1 版本
Accept: application/prs.beautyblog.v1+json
访问 v2 版本
Accept: application/prs.beautyblog.v2+json

API_PREFIX 和 API_DOMAIN

项目可以使用前缀或者子域名的方式来区分 API 与 Web 等页面访问地址，，两者有且只有一个。
添加前缀，通过 www.beautyblog.com/api 来访问 API。

1	API_PREFIX=api

或者有可能单独配置一个子域名api.beautyblog.com

1	API_DOMAIN=api.larabbs.com

通过 api.larabbs.com 来访问 API。

API_VERSION ：默认API版本，当我们没有传 Accept 头的时候，默认访问该版本的 API

API_STRICT ：严格模式,如果开启，则必须使用 Accept 头才可以访问 API，也就是说直接通过浏览器，访问某个 GET 调用的接口将会报错

测试接口

打开routes/api.php文件，路由需要使用 Dingo\Api\Routing\Router 注册

$api = app('Dingo\Api\Routing\Router');

$api->version('v1', function($api) {
    $api->get('version', function() {
        return response('this is version v1');
    });
});

然后使用postman，输入url: http://beautyblog.test/api/version 选择get方法，如果返回 this is version v1 正常。

提示: 由于路由被 DingoApi 接管了，如果将来部署上线后你需要缓存路由，可以使用 php artisan api:cache
代替 php artisan route:cache ，本地测试请不要执行这个命令。

小凡